Developer CD Series 1996 February: Tool Chest

home *** CD-ROM | disk | FTP | other *** search

/ Developer CD Series 1996 February: Tool Chest / Apple Developer CD Series Tool Chest February 1996 (Apple Computer)(1996).iso / Sample Code / AppsToGo / DTS.Lib / DTS.Lib.headers / Window2.h < prev

Wrap

C/C++ Source or Header | 1994-09-22 | 50.2 KB | 1,340 lines | [TEXT/KAHL]

#ifndef __WINDOW2__ #define __WINDOW2__ #ifndef __TYPES__ #include <Types.h> #endif #ifdef __cplusplus extern "C" { #endif OSErr DoNewWindow(FileRecHndl frHndl, WindowPtr *retWindow, WindowPtr relatedWindow, WindowPtr behind); /* ** ¶ Create window for AppsToGo document. ** ** INPUT: frHndl This file reference is used to create a window. At this ** point there is (or should be) window creation information ** in the file reference. If you are using the AppsToGo ** application editor to create your documents, then the ** information is in the file reference at this point. ** relatedWindow This window is what is used to determine which monitor ** the window should be created on. If there is a related ** window passed in, DoNewWindow determines which monitor ** holds most of the window. That monitor is then the ** target monitor for the new window. ** behind This window is the window that the new window is created ** behind. Pass in -1 if the window is to be created as ** the frontmost window. Pass in 0 if it is to be created ** as the backmost window. ** OUTPUT: retWindow Return the created window here. If you don’t care to ** know, then pass in nil. ** RESULT: OSErr If an error is returned, then no window was created. ** ** This function is called by the application or framework at appropriate times to ** give a document a window. To create a document window, first a document is created ** by the application via NewDocument or OpenDocument. If this succeeds then the ** application needs to create a window for the document. To do this, the application ** calls DoNewWindow. DoNewWindow calls the content initialization procedure, which ** by default is InitContent. If you want a different content initialization ** procedure, replace the default procedure pointer initContentProc with your own. ** Normally however, you will just place your own content initialization procedure in ** the function InitContent. It is possible though that your application has more ** than one document type and window type. If this is the case, then you may very ** well want an alternate content initialization procedure. If you do, you will want ** to replace the default procedure pointer after the NewDocument or OpenDocument ** call and before the call to DoNewWindow. (You may place the code for replacing the ** content initialization procedure and imaging procedure in the function InitDocument. ** The defaults are already established at that point. You would just replace them ** with the alternates. ** ** __________ ** ** Also see: NewDocument, OpenDocument. */ void NewWindowTitle(WindowPtr window, StringPtr altTitle); /* ** ¶ Change the window/document title. ** ** INPUT: window ** altTitle ** ** Call this function if you want to change the title of the window. ** If you pass in nil, the window title will be gotten from the FSSpec of the ** document. If you pass in an alternate title in altTitle, that will be used ** instead of the document name. */ Boolean DisposeAllWindows(void); /* ** ¶ Dispose the windows, giving user the chance to abort. ** ** This function iterates through all of the windows and calls DisposeOneWindow ** on each one. If DisposeOneWindow returns that the user canceled the closing ** of a window that needed saving, then DisposeAllWindows also aborts. This ** is used when an application is quitting. */ Boolean DisposeOneWindow(WindowPtr window, short saveMode); /* ** ¶ Dispose one window, giving the user the chance to abort. ** ** INPUT: window ** saveMode ** ** This function does exactly as you would expect. The saveMode indicates ** whether the window is being closed due to a close request, or due to the ** application being quit. If true is returned, then disposing of the window ** was successful. If false is returned, the user may have canceled the close ** due to the document needing to be saved, a dialog as such popping up, and ** the user clicking cancel. ** ** If the user says it is okay to dispose the window, DisposeOneWindow calls ** the window’s FreeWindow and FreeDocument procedures to give the application ** a chance to release application-specific memory associated with the window ** and document. ** ** __________ ** ** Also see: DisposeAllWindows. */ WindowPtr SetFilePort(FileRecHndl frHndl); /* ** ¶ Given file, set the port to the document’s port. ** ** INPUT: frHndl ** ** This function sets the current port for the designated file. It also returns ** the old port so that the port can be restored, if so desired. Note that you ** can always get the window for a document by simply dereferencing the doc handle ** as follows: window = (*frHndl)->fileState.window; ** Keep in mind that a document doesn’t have to have a window. If you created the ** document yourself via NewDocument or OpenDocument, the document doesn’t have a ** window assigned to it yet, and therefore the above dereference will return nil. */ void DoResizeWindow(WindowPtr window, short oldh, short oldv); /* ** ¶ Called after a window is resized via grow or zoom. ** ** INPUT: window ** oldh ** oldv ** ** This function is called when a window is resized. This function may need ** to know the old size of the window. The new size is determined by the ** dimensions of the window that was resized. It moves and resizes the ** document scrollbars and growIcon (if any) to reflect the new size of ** the window. It then calls the procedure stored in the procPtr field ** resizeContentProc, in case there is additional sizing necessary for the window. ** The default resizeContentProc is ResizeContent. If you wish an alternate ** resizeContentProc, then you can replace the default in the function ** InitDocument, as the default is already established at this point. */ void GetWindowChange(WindowPtr window, short oldh, short oldv, short *dx, short *dy); /* ** ¶ Given the old size, this returns the difference between the old size and the new size. ** ** INPUT: window ** oldh ** oldv ** OUTPUT: dx ** dy ** ** This function returns the difference between the old window size and the new window ** size. Pass in the old window size, and this function looks up the current size, ** gets the difference, and returns it. */ void DoUpdateSeparate(WindowPtr window, RgnHandle *contRgn, RgnHandle *frameRgn); /* ** ¶ Separates the updateRgn into a frameRgn and a contentRgn. ** ** INPUT: window ** OUTPUT: contRgn ** frameRgn ** ** This function separates the update region into two portions. One portion is ** the frame area, which consists of document scrollbars and growIcon (if any), plus ** an optional application-defined frame area. The other portion is the rest of the ** window content that needs updating. This separation is so that the document ** scrollbars can be updated first, and then this area can be clipped out of the rest ** of the updating so that the window content doesn’t draw over the document ** scrollbars and growIcon. The clipping is managed with just the visRgn. This frees ** up the clipRgn for application specific clipping. Note that if either region ** is computed to be empty, DoUpdateSeparate will return a nil for that handle. ** ** __________ ** ** Also see: BeginContent, EndContent, BeginFrame, EndFrame, DoCalcScrollRgn, DoCalcFrameRgn. */ void BeginContent(WindowPtr window); /* ** ¶ Used instead of BeginUpdate to draw to just the content area. ** ** INPUT: window ** ** This function clips out the document scrollbars and growIcon from the updatable ** area. It also sets the origin of the port to the current document scrollbar ** values. BeginContent must be balanced by a call to EndContent. BeginContent calls ** BeginUpdate, and BeginUpdate calls can’t be nested. Due to this, BeginContent has ** a usage counter, which prevents nested calls to BeginUpdate. BeginContent clips ** out the document scrollbar and growIcon area without involving the clipRgn so that ** the application is free to use the clipRgn as it sees fit. The only caveat is that ** you can not modify the updateRgn between the BeginContent and EndContent calls, as ** anything contributed to the updateRgn between these calls will be lost. If you ** need to do this, accumulate the areas in a separate region, call EndContent, and ** then call InvalRgn. ** ** __________ ** ** Also see: BeginFrame, EndFrame, DoCalcScrollRgn, DoCalcFrameRgn, DoUpdateSeparate. */ void EndContent(WindowPtr window); /* ** ¶ Used instead of EndUpdate to balance BeginContent calls. ** ** INPUT: window ** ** Calls to BeginContent must be balanced. They also don’t nest. EndContent undoes ** the clipping of the frame area that BeginContent invoked. ** ** __________ ** ** Also see: BeginFrame, EndFrame, DoCalcScrollRgn, DoCalcFrameRgn, DoUpdateSeparate. */ void BeginFrame(WindowPtr window); /* ** ¶ Used instead of BeginUpdate to draw to just the frame area. ** ** INPUT: window ** ** This function does the same thing as BeginContent, except that it clips out everything ** except the frame area. The frame area consists of the sidebars and any additional ** application-defined frame area. The application-defined frame area is defined in the ** AppWannabe function CalcFrameArea. Also, the origin is set to -16384,0, which is the ** coordinate space for sidebar controls created with the AppsToGo application editor. ** Calls to BeginFrame must be balanced with calls to EndFrame. ** ** __________ ** ** Also see: BeginContent, EndContent, DoCalcScrollRgn, DoCalcFrameRgn, DoUpdateSeparate. */ void EndFrame(WindowPtr window); /* ** ¶ Used instead of EndUpdate to balance BeginFrame calls. ** ** INPUT: window ** ** Calls to BeginFrame must be balanced. They also don’t nest. EndFrame undoes the ** clipping of the frame area that BeginFrame invoked. ** ** __________ ** ** Also see: BeginContent, EndContent, DoCalcScrollRgn, DoCalcFrameRgn, DoUpdateSeparate. */ void AdjustScrollBars(WindowPtr window); /* ** ¶ Modify scrollbar values to reflect other window changes. ** ** INPUT: window ** ** You call this function whenever you need the scrollbars to reflect the window ** state and position. If you change the sidebar sizes or indent sizes by hand, ** you will need to call this. Generally an application will not have to call this ** directly, as there are functions for scrolling, setting sidebar sizes, indent ** sizes, etc. */ void GetContentOrigin(WindowPtr window, Point *contOrg); /* ** ¶ Return the origin of the content of the window. ** ** INPUT: window ** OUTPUT: contOrg ** ** This function returns the origin of the content of the window. The value ** is gotten from the current value of the document scrollbars. If a scrollbar ** is missing, the control value for that scrollbar is assumed to be 0. Note that ** if you have sidebars in your document, the origin value has the sidebar value ** subtracted. For example: You have a top sidebar of 32 pixels, and the vertical ** scrollbar has a control value of 0. This will return you a vertical origin ** of -32. ** ** __________ ** ** Also see: SetContentOrigin. */ void SetContentOrigin(WindowPtr window, long newh, long newv); /* ** ¶ Change the origin of the content of the window. ** ** INPUT: window ** newh ** newv ** ** This function allows you to change the value of the document scrollbars, and by doing ** this, the document is scrolled to reflect the change, and an update event is generated ** for the document scroll. Note that if you are using sidebars, you will have to subtract ** the value of the sidebar to get the expected results. Also note that this function ** accepts long values. You may have a proc for handling longs for the document scrollbars. ** The proc is stored in the refCon of the document scrollbars. If the refCon ** value of the document scrollbars is 0, then it is assumed that values from 0 ** to 32767 are adequate for document scrolling. ** ** __________ ** ** Also see: GetContentOrigin. */ void GetContentRect(WindowPtr window, Rect *contRct); /* ** ¶ Get bounding rect of the content area of the window. ** ** INPUT: window ** OUTPUT: contRct ** ** This function returns a rectangle that represents the content area of the ** window less the scrollbar and sidebar areas. */ void SetDocSize(FileRecHndl frHndl, long hSize, long vSize); /* ** ¶ Set new document size and make approprate adjustments to the window. ** ** INPUT: frHndl ** hSize ** vSize ** ** This function sets the document size to the new designated size. It also ** makes appropriate adjustments to the scrollbars to reflect the new size. ** SetDocSize will not cause the window to scroll, even if you set the doc ** size much smaller. If the document shrinks such that the bottom of the ** document is above the top of the window, it is not automatically scrolled ** into place. (This is the same behavior as system 7 finder.) When the ** user scrolls the document into view, the scrollbar range will be reduced ** so that the user can’t scroll the document back out of view. */ void SetSidebarSize(FileRecHndl frHndl, short newLeft, short newTop); /* ** ¶ Change the size of one or both sidebars. Window is adjusted accordingly. ** ** INPUT: frHndl ** newLeft ** newTop ** ** This function is used to set the size of the sidebars. This is particularly ** useful for being able to show and hide a tool palette, or if you are using ** OCE and want to show a mailer at the top of your window. The sidebar value ** should initially be set in File.c, along with other document initialization. ** If you wish to change only one of the two sidebar sizes, send in a value of ** kwNoChange for the one that is not to change. ** ** __________ ** ** Also see: SetScrollIndentSize. */ void SetScrollIndentSize(FileRecHndl frHndl, short newh, short newv); /* ** ¶ Change the size of the scroll indent area. Window is adjusted accordingly. ** ** INPUT: frHndl ** newh ** newv ** ** This function is used to set the size of the scrollbar indention. The scrollbar ** indentnion allows you to put status information or document display related ** tool icons in line with the scrollbar. They are considered part of the frame, ** as document scrollbars, the grow icon, and sidebars are. The scrollbar indent ** value should initially be set in File.c, in the same fashion as sidebar values ** are set. If you wish to change only one of the two scrollbar indent, send in a ** value of kwNoChange for the one that is not to change. ** ** __________ ** ** Also see: SetSidebarSize. */ FileRecHndl GetNextDocument(WindowPtr window, OSType sftype); /* ** ¶ Iterator to walk window list and return the next document of correct type. ** ** INPUT: window ** sftype ** RESULT: frHndl ** ** This function returns the file reference for the next application window ** of the designated kind. If the window paramater is passed in as nil, it ** finds the top-most window whose document type matches the requested OSType. ** If the window parameter is passed in as non-nil, it returns the next window. ** If there is no next window found, it returns nil. The sftype parameter ** restricts the finding of a window to a particular type. If 0 is passed in ** for sftype, then any application window will match. ** ** __________ ** ** Also see: GetNextWindow, GetPreviousWindow. */ WindowPtr GetNextWindow(WindowPtr window, OSType sftype); /* ** ¶ Iterator to walk window list and return the next document window of correct type. ** ** INPUT: window ** sftype ** ** This function behaves the same as GetNextDocument, but returns a window pointer ** instead of a file reference. ** ** __________ ** ** Also see: GetNextDocument, GetPreviousWindow. */ WindowPtr GetPreviousWindow(WindowPtr window); /* ** ¶ Return the window in front of indicated window. ** ** INPUT: window ** ** Returns the window in front of the window passed in. If there is no window ** in front, it returns -1, not nil. -1 is typically used to indicate the front ** of the window list, whereas nil is used to indicate the back. This is done to ** stay consistent with the expectations of the toolbox. ** ** __________ ** ** Also see: GetNextDocument, GetNextWindow, GetPreviousWindow. */ void DoZoomWindow(WindowPtr window, EventRecord *event, short zoomDir); /* ** ¶ AppsToGo smart zoom. ** ** INPUT: window ** event ** zoomDir ** ** This function handles zooming of the document window. It zooms it to the ** current monitor, up to the size of the document data. */ RgnHandle DoCalcFrameRgn(WindowPtr window); /* ** ¶ Calculate region that encompasses entire window frame area. ** ** INPUT: window ** ** This function calculates the region that encompasses the frame area of the ** document. The frame area consists of the document scrollbars, growIcon, sidebars, ** and an optional application-defined frame area. The region is generated in global ** coordinates. Since the frame region may encompass more than the ** DTS.framework-supported scrollbars and growIcon, a procedure is first called to see ** if there is anything additional in the frame region. The field calcFrameRgnProc ** holds the procedure pointer that contributes any extra to the frame region. This ** function is passed an empty region. If there is no additional contribution to the ** frame region, then the region should be left empty. Once this procedure is ** returned from, the remaining frame portion is added to this region. The remaining ** portion would consist of DTS.framework document scrollbars and a growIcon, if there ** are any for this window. The field calcFrameRgnProc is initialized to the ** default value CalcFrameRgn. If you wish an alternate drawFrameProc, then you ** can replace the default in the function InitDocument, as the default is ** already established at this point. ** ** __________ ** ** Also see: DoCalcContentRgn, DoCalcScrollRgn. */ RgnHandle DoCalcScrollRgn(WindowPtr window); /* ** ¶ Calculate the region that encompasses the document scrollbars and growIcon. ** ** INPUT: window ** ** This function calculates the region that encompasses the document scrollbars ** and growIcon (if any). The region is generated in global coordinates. ** ** __________ ** ** Also see: DoCalcFrameRgn, DoCalcContentRgn. */ void DoContentClick(WindowPtr window, EventRecord *event, Boolean firstClick); /* ** ¶ Process a content click. May call application to help. ** ** INPUT: window ** event ** firstClick ** ** This function is called whenever the content portion of a window is clicked in. ** It simply calls the procedure pointer stored in the field contentClickProc. ** The field contentClickProc is initialized to ContentClick. If you wish ** an alternate contentClickProc, then you can replace the default in the function ** InitDocument, as the default is already established at this point. The ** boolean firstClick is true if you chose this window to handle first clicks, and ** if the click is actually a first click in the window. A first click means that ** the window content was clicked on, but the window was not the front window. The ** window has already been brought to the front, but you may wish the click to also ** be handled as a content click. ** ** Note that if you call DoContentClick directly, you need to handle the other ** aspects of mouseDown events. Generally you will simply want to call DoMouseDown ** from your application. If the mouseDown end up being in the content of a window, ** DoMouseDown will call DoContentClick. ** ** __________ ** ** Also see: DoKeyDown, DoUpdate. */ void DoDragWindow(WindowPtr window, EventRecord *event, Rect bounds); /* ** ¶ AppsToGo DragWindow code. Use this instead of DragWindow. ** ** INPUT: window ** event ** bounds ** ** This function is used to drag a window. We can’t use the toolbox function ** DragWindow, as the DTS.framework supports palettes. Since we are supporting ** palettes, we have to be able to drag a window that isn’t the front, and bring ** it to the front of windows of its kind. There is no way to coerce DragWindow ** to do this. */ void DoDrawFrame(WindowPtr window, Boolean activate); /* ** ¶ Draw the entire frame of a window. Application may also be called for part. ** ** INPUT: window ** activate ** ** This function may be called when an update event occurs for the window. ** If the update region intersects the frame region (calculated by DoCalcFrameRgn), ** then a frame update occurs and this function is called. It redraws the ** document scrollbars and growIcon (if any) and then calls the procedure stored ** in the field drawFrameProc, which has a default value of DrawFrame. If you wish ** an alternate drawFrameProc, then you can replace the default in the function ** InitDocument, as the default is already established at this point. */ OSErr DoFreeDocument(FileRecHndl frHndl); /* ** ¶ Opportunity to release a document’s additional memory. ** ** INPUT: frHndl ** RESULT: OSErr ** ** This is called to generically call the document’s freeing procedure. This document ** is being disposed of, and any custom memory usage needs to be deallocated. The ** frHndl itself will be disposed of, but any handle references that it contains ** need to be freed within the document’s freeing procedure. The default freeing ** procedure is called FreeDocument. ** ** Note that DoFreeDocument is called by DisposeOneWindow. This means that the ** application will get a chance to dispose of any related memory due to a call to ** DisposeOneWindow. */ OSErr DoFreeWindow(FileRecHndl frHndl, WindowPtr window); /* ** ¶ Opportunity to release a window’s additional memory. ** ** INPUT: frHndl ** window ** RESULT: OSErr ** ** This is called to generically call the document’s window freeing procedure. ** The window is going to be disposed of, and there may be related tasks to disposing ** of the window. A document may have related windows or views. This is where you ** would dispose of the related windows. The default window freeing procedure is ** called FreeWindow. ** ** Note that DoFreeWindow is called by DisposeOneWindow. This means that the ** application will get a chance to dispose of any related memory due to a call to ** DisposeOneWindow. */ OSErr DoImageDocument(FileRecHndl frHndl); /* ** ¶ Application window’s imaging procedure (to either window or printer). ** ** INPUT: frHndl ** RESULT: OSErr ** ** This function is called whenever the content portion of a window needs to be ** updated or printed. It simply calls the procedure pointer stored in the field ** imageProc. The field imageProc is initialized to ImageDocument. If you wish ** an alternate imageProc, then you can replace the default in the function ** InitDocument, as the default is already established at this point. ** Note that when the document’s imageProc is called, only the content can be ** drawn to. BeginContent is called prior to calling the imageProc, and ** EndContent is called upon return. */ OSErr DoInitContent(FileRecHndl frHndl, WindowPtr window); /* ** ¶ Application’s opportunity to initialize window content. ** ** INPUT: frHndl ** window ** RESULT: OSErr ** ** The window has been created, and is about to be displayed. At this time, this ** function is called. It generically calls the window content initialization ** procedure indicated within the frHndl. The default window content initialization ** procedure is called InitContent. */ Boolean DoKeyDown(EventRecord *event); /* ** ¶ Process key event. Framework may call application to finish event. ** ** INPUT: event ** ** DoKeyDown is first called by the application. If the key is a menu key, the ** AppWannabe function DoMenuCommand is called. If the key isn’t a menu ** key, DoKeyDown starts walking through the window list, giving each window an ** opportunity to handle the key. Windows can handle it, eat it, or pass the key ** through to the next window. ** It gives each window a chance to handle the key by calling the key handling ** procedure stored in the frHndl. The default procedure is called KeyDown. Here ** are the rules for the window key handling procedure: ** ** 1) If it handles the key, it returns true. This completes the key handling. ** 2) If it doesn’t handle the key, it returns false. However, there are two ** situations for not handling the key: ** a) The window wants windows behind it to try handling the key. ** b) The window wants nobody else to look at the key. ** This is what the boolean passThrough is for. If the procedure wishes the next ** window to have a look at the key, it should set the boolean passThrough to true. ** passThrough is already initialized to false prior to calling the procedure, ** which is the common case, so the window key handling procedure only has to ** worry about setting it true. ** ** If the window never processes keys and always passes them through to the next ** window, the contentKeyProc field in the frHndl should be set to nil. This will ** indicate to DoKeyDown that all keys should be passed through this window. ** DTS.Draw has such a window. The palette window doesn’t accept keys. They are ** passed through to document windows that are behind the palette. */ void DoMouseDown(EventRecord *event); /* ** ¶ Process mouseDown event. Framework may call application to finish event. ** ** INPUT: event ** ** Call this whenever a mouse down event occurs in the application. Everything is ** handled. Here’s what DoMouseDown may do, and what it depends on: ** It handles: ** inContent ** inDrag ** inGoAway ** inGrow ** inMenuBar ** inSysWindow ** inZoomIn ** inZoomOut ** ** inContent: ** a) If the window clicked on is a DA window, then bring the window to the front. ** b) If the window is the top-most and it is a document window, then ** DoContentClick is called. ** c) If the window is not the top-most of its kind (palette,dialog,document), ** then it is made the top-most of its kind. If the window has the ** kwDoFirstClick bit set, then DoContentClick is called, indicating to it ** that this click is a first click (window-to-front click). ** ** inDrag: ** The window is dragged. When released, if the command key was not held down at ** the time of the click, the window is made the top-most window of its kind. ** ** inGoAway: ** The go-away is tracked. If the document is dirty, then the user is asked if ** the document should first be saved. The user can save, discard, or cancel. ** All cases are handled. ** ** inGrow: ** The window is grown. Scrollbar adjustments are handled as they are in the ** 7.0 finder. ** ** inMenuBar: ** MenuSelect is called, then the AppWannabe function DoMenuCommand is called ** with the result of MenuSelect. ** ** inSysWindow: ** SystemClick is called. ** ** inZoomIn: ** inZoomOut: ** The window is grown, according to the human-interface guidelines for zooming. ** The window is zoomed on the monitor that contains most of the window. The zoom ** size is limited by the document size. All of these details are handled. */ short MapMItem(short menuID, short menuItem); /* ** ¶ Convert hard menuItem ID to a soft ID. ** ** INPUT: menuID The menu ID ** menuItem The menuItem, as returned by the Menu Manager (hard value) ** RESULT: short The soft menu value. ** ** This function converts a menu item hard-id (one returned by the toolbox) to a ** soft-id (defined in the 'STR#' resource associated with the menu). If there is ** a 'STR#' resource defined with the same id as the menu, it is assumed to be ** for the purpose of converting hard-id values to soft-id values. ** ** __________ ** ** Also see: UnmapMItem. */ short UnmapMItem(short menuID, short menuItem); /* ** ¶ Convert soft menuITem ID to a hard ID. ** ** INPUT: menuID ** menuItem ** RESULT: short ** ** This function is the logical reverse of MapMItem. */ OSErr DoReadDocument(FileRecHndl frHndl); /* ** ¶ Calls document’s read-document procedure, which reads the document. ** ** INPUT: frHndl ** RESULT: OSErr ** ** DoReadDocument calls the specific read document procedure for the document. ** The specific procedure is stored in the frHndl field readDocumentProc. The ** default value for readDocumentProc is ReadDocument. It is the responsibility ** of the readDocument procedure to call the readDocumentHeader procedure. This is ** done by calling DoReadDocumentHeader from within the readDocumentProc. */ OSErr DoReadDocumentHeader(FileRecHndl frHndl); /* ** ¶ Calls document’s document read-header procedure, which reads the header. ** ** INPUT: frHndl ** RESULT: OSErr ** ** DoReadDocumentHeader calls the specific read document header procedure for the ** document. The specific procedure is stored in the frHndl field ** readDocumentHeaderProc. The default value for readDocumentHeaderProc ** is DefaultReadDocumentHeader. */ OSErr DefaultReadDocumentHeader(FileRecHndl frHndl); /* ** ¶ Read the default document header format. ** ** INPUT: frHndl ** RESULT: OSErr ** ** This function reads in the default header for a file. The header information is ** described by the structure DocHeaderInfo. The typedef for this structure is in the ** file DTS.Lib.h. This block of header information is saved at the beginning of the ** file. It is written to the data fork. If you want the header information saved in ** the resource fork, you will have to have a custom readDocumentHeaderProc and ** writeDocumentHeaderProc. You can then simply read and write using the resource ** fork, instead of the data fork, as the defaults do. */ OSErr DoWriteDocument(FileRecHndl frHndl); /* ** ¶ Calls document’ write document procedure. ** ** INPUT: frHndl ** RESULT: OSErr ** ** DoWriteDocument calls the specific write document procedure for the document. ** The specific procedure is stored in the frHndl field writeDocumentProc. The ** default value for writeDocumentProc is WriteDocument. It is the responsibility ** of the writeDocument procedure to call the writeDocumentHeader procedure. This is ** done by calling DoWriteDocumentHeader from within the writeDocumentProc. */ OSErr DoWriteDocumentHeader(FileRecHndl frHndl); /* ** ¶ Calls document’s write-header procedure. ** ** INPUT: frHndl ** RESULT: OSErr ** ** DoWriteDocumentHeader calls the specific write document header procedure ** for the document. The specific procedure is stored in the frHndl field ** writeDocumentHeaderProc. The default value for writeDocumentHeaderProc ** is DefaultWriteDocumentHeader. */ OSErr DefaultWriteDocumentHeader(FileRecHndl frHndl); /* ** ¶ Writes the default header format. ** ** INPUT: frHndl ** RESULT: OSErr ** ** This function writes out the default header for a file. The header information is ** described by the structure DocHeaderInfo. The typedef for this structure is in the ** file DTS.Lib.h. This block of header information is saved at the beginning of the ** file. It is written to the data fork. If you want the header information saved in ** the resource fork, you will have to have a custom readDocumentHeaderProc and ** writeDocumentHeaderProc. You can then simply read and write using the resource ** fork, instead of the data fork, as the defaults do. */ void DoResizeContent(WindowPtr window, short oldh, short oldv); /* ** ¶ Called after a window is resized. This is make related changes to the content. ** ** INPUT: window ** oldh ** oldv ** ** This function is called when a window has been resized. It is possible that window ** contents have to be adjusted to match the new window size. DoResizeContent ** handles this. DoResizeContent uses a procedure stored in the frHndl field ** resizeContentProc. If resizeContentProc is not nil, then the procedure is called. ** The default value for resizeContentProc is ResizeContent. */ void DoScrollFrame(WindowPtr window, long dx, long dy); /* ** ¶ Scroll a document’s frame area. ** ** INPUT: window ** dx ** dy ** ** Some applications may need to scroll the "frame" of the document along with the ** document contents. This is common for applications with rulers, or other similar ** sidebar items. DoScrollFrame is called when document scrolling has occured. ** DoScrollFrame uses a procedure stored in the frHndl field scrollFrameProc. ** If scrollFrameProc is not nil, then the procedure is called. The default value ** for scrollFrameProc is ScrollFrame. */ void DoUndoFixup(FileRecHndl frHndl, Point contOrg, Boolean afterUndo); /* ** ¶ Part of the undo mechanism. This dispatches to the document’s undo fixup. ** ** INPUT: frHndl ** contOrg ** afterUndo ** ** This function is called by the hierarchical document package in response to an ** undo/redo operation. It is called prior to any undo information being applied ** to the document so that you can prepare the document for an undo. It is also ** called after all undo tasks are performed on the document. This last call is a ** chance for any additional cleanup that might have to occur. Commonly this second ** call is used to reimage the document to show the document undone/redone. ** DoUndoFixup doesn’t actually do the work, as it doesn’t know what kind of ** document it was called for. It simply looks in the frHndl at the field ** undoFixupProc. If undoFixupProc is not nil, then the procedure is called. ** The default value for undoFixupProc is UndoFixup. */ void CleanSendBehind(WindowPtr window, WindowPtr afterWindow); /* ** ¶ A better SendBehind, which is needed for floating palettes, etc. ** ** INPUT: window ** afterUndo ** ** This function is exactly what it would seem by the name. SendBehind has some ** problems in that it causes too much repainting of windows. This function allows ** you to change the layer of a window very cleanly. It also calls HiliteWindows, ** which walks the window list and adjusts window hilighting for the various types ** of windows. The top-most of a type is hilited, and all other windows of that ** type are unhilited. */ void CleanSendInFront(WindowPtr window, WindowPtr beforeWindow); /* ** ¶ Bring a window in front of another, while handling floating palettes, etc. ** ** INPUT: window ** beforeWindow ** ** Again, this is exactly what it would seem. See CleanSendBehind for ** more information. */ void HiliteWindows(void); /* ** ¶ Makes sure that the hiliting of windows is correct. ** ** This function is called to adjust the hilites of all windows. Since DTS.framework ** supports palettes, there is possibly more than one hilited window. The window ** manager doesn’t want to play this game, so certain additional functions had to be ** written. Basically, if you are using palettes, don’t make any window manager calls ** that change window hiliting. Use CleanSendBehind and CleanSendInFront. These ** take care of window shuffling correctly. Of course, there are calls you can’t ** avoid, such as closing a window. If you do these operations directly, call ** HiliteWindows afterwards. */ void UnhiliteWindows(void); /* ** ¶ Unhilite all windows. This is done before bringing up a modal dialog, for example. ** ** This is called to unhilite all windows. DTS.framework allows for multiple hilited ** windows. All of them have to be unhilited prior to bringing up a modal dialog or ** alert. Call this to unhilite all windows, do the modal dialog or alert, and then ** call HiliteWindows to set the hiliting back to normal. */ void DoUpdate(WindowPtr window); /* ** ¶ Update the window. Do this in response to an update event. ** ** INPUT: window ** ** This is called when an update event is received for a window. First, the ** updateRgn is separated into two parts. Part 1 holds the window frame area, ** if any. This is the area that might hold the scrollbars, grow icon, and ** any other application-specific frame parts. This is drawn first. Once ** this is done, the remainder of the updateRgn is drawn. This allows us to ** handle all of the frame clipping without using the clipRgn. By freeing up ** the clipRgn, we allow the application to use it without having to share. */ void DoSetCursor(Cursor *cursor); /* ** ¶ Main application cursor-setting procedure. ** ** INPUT: cursor ** ** Call this function to correctly set the cursor and to inform DTS.framework that ** you have specifically set the cursor. This is used when you temporarily want to ** set the cursor, such as just before a slow operation. For a slow operation, you ** may want to put up the wait cursor. Use DoSetCursor for this, and then when the ** operation is over and program control returns to the main event loop, the cursor ** will be recalculated to the current cursor for the mouse position. */ CursPtr DoSetResCursor(short crsrID); /* ** ¶ Given an ID, instead of a pointer, set the cursor. ** ** INPUT: crsrID ** RESULT: CursPtr ** ** This function serves the same purpose as DoSetCursor, except that you pass in ** a resID, instead of a cursor pointer. The resource is loaded, the cursor is then ** copied into permanent memory, and then DoSetCursor is called with a pointer to ** the cursor image. */ void DoWindowCursor(void); /* ** ¶ Iterates through the windows, giving the document a chance to set the cursor. ** ** Call this function to calculate what the cursor should be for various windows. ** The result of this function is to set the cursor based on the current mouse ** position. In addition to setting the cursor, the cursor region is calculated. ** The cursor region is kept in the global variable gCursorRgn. ** This function walks the window list, and for each document window, it calls the ** window’s cursor handling procedure. The cursor handling procedure is stored in ** the frHndl field windowCursorProc. ** Here are the rules for cursor and gCursorRgn determination: ** ** 1) See if the mouse position is currently inside the gCursorRgn. If so, leave. ** 2) Since the mouse position is outside the current gCursorRgn, we need to ** recalculate the cursor. Set the gCursorRgn to wide-open. From now on, we ** will eliminate areas from gCursorRgn that don’t apply to the new mouse ** location and new cursor. ** 3) For each visible window (starting with the front window): ** a) If the windowCursorProc is nil and the mouse position is over the structure ** region of the window, set the cursor to an arrow and intersect the gCursorRgn ** with the structure region of the window. This limits the cursor to the area ** of the window that is visible. ** b) If the windowCursorProc is nil and the mouse position is outside the ** structure region of the window, diff out the structure region from ** gCursorRgn and proceed to the next visible window in the window list. ** c) If the windowCursorProc is not nil, call the procedure. Note that the ** procedure is called whether or not the mouse location is over the window. ** This is to allow the procedure to determine if it should be the last ** window checked. ** The proc’s job is as follows: ** 1) If the cursor is over a position that is determined by the window, then ** the proc removes other areas from gCursorRgn. Note that it should not ** simply set the area to what it "thinks" is the correct area. This window ** may not be the front-most. Other windows will have already been ** subtracted from gCursorRgn. The resultant gCursorRgn is the correct ** cursor area, and should be passed to WaitNextEvent calls in the ** application. Also, the cursor should be set to the correct cursor, of ** course. You should also return true, as the cursor has been determined. ** The rule of thumb for what you should do to the gCursorRgn is that you ** should calculate the cursor region as if the window was the top window. ** Once this is done, intersect the gCursorRgn with this region. The result ** should be stored in gCursorRgn. ** Since you determined a cursor and gCursorRgn in this case, you should ** return true. Returning true indicates to DoWindowCursor that the ** cursor has been determined, and that it should stop processing windows. ** 2) If the cursor is not over a position for this window, then you should ** return. You will either pass back true or false. If you don’t wish ** windows behind this window to have a shot at cursor determination, then ** return true. This states that the cursor is "determined". It is, in the ** sense that no further determination will occur. If you return false, then ** other windows get a shot at determining the cursor. If there are no other ** windows, then the cursor is set to an arrow, and gCursorRgn is set to the ** area that is outside all windows for the application. ** (Common case:) If you don’t want windows behind this one to determine ** the cursor: ** a) Set the cursor to an arrow. Since you are outside this window, the ** cursor should be an arrow. The cursor may be over the desktop or ** menubar, or some other window that isn’t the top-most window. All of ** these cases should have an arrow cursor. Also, you need to diff out ** the window’s structure region from gCursorRgn. By diffing it out, ** you will get mouse-moved events when the cursor is moved back over ** this window. ** b) Return true. This tells DoWindowCursor that the cursor has ** been determined. ** (Uncommon case:) If you want windows behind this one to possibly ** determine the cursor: Return false. That’s it. DTS.framework will ** automatically remove the structure region for this window from ** gCursorRgn if you return false. If you return false, DTS.framework ** proceeds to the next window, if there is one. If there are no more ** windows behind this one, then DTS.framework sets the cursor to an ** arrow, and the resultant gCursorRgn will have all of the structure ** regions for the windows removed from it. */ WindowPtr FrontWindowOfType(long wkind, Boolean firstVis); /* ** ¶ Get front-most window meeting criteria. ** ** INPUT: wkind ** firstVis ** RESULT: WindowPtr ** ** Since DTS.framework supports three distinct categories of windows ** (document/palette/dialog), it is often necessary to get the front-most ** window of a certain type. Use this function to accomplish this. Basically, ** this takes the place of FrontWindow if you have more than one category of ** window in your application. */ short HCenteredAlert(short alertID, WindowPtr relatedWindow, ModalFilterUPP filter); /* ** ¶ Put up an alert, and also make sure that hiliting of other windows is correct. ** ** INPUT: alertID ** relatedWindow ** filter ** RESULT: short ** ** This function gets an alert, and handles hiliting of windows correctly. ** The reason for this function is that there may be more than one hilited ** window due to the possibility of floating palettes. The calls to UnhiliteWindows ** and HiliteWindows make sure that while the alert is up, there are no other ** hilited windows. */ OSErr GetWindowFormats(void); /* ** ¶ Read in and unflatten resource 'WFMT' #128. ** ** RESULT: OSErr ** ** This function gets the application window formats that were created with ** the AppsToGo application editor. The window formats are stored in the resource ** 'WFMT' id #128. They are first read in, and then they are unflattened ** by calling HReadWindowFormats. */ OSErr HReadWindowFormats(Handle wfmt); /* ** ¶ Unflattens a window-format handle into separate hierarchical document objects. ** ** INPUT: wfmt ** RESULT: OSErr ** ** This function is called to unflatten a window-format handle into separate ** hierarchical document objects. The assumption is that there is only one ** of these multiple window definitions, and therefore if there is already ** one in the global gWindowFormats, it is disposed of. This is exactly the ** behavior needed by the AppsToGo application editor. */ OSErr GetSeparateWFMT(OSType sftype, short *numAdded); /* ** ¶ Add (or remove) window-format resource definition to global gWindowFormats. ** ** INPUT: sftype ** OUTPUT: numAdded ** RESULT: OSErr ** ** This function is called to add (or remove) a window-format resource definition ** to the global gWindowFormats. The purpose of this is to be able to break up the ** single 'WFMT' id #128 resource, which may get quite large for some applications. ** NewDocumentWindow and AddControlSet automatically call GetSeparateWFMT ** for you. If the document definition is in a separate 'WFMT' resource, ** then that definition is added to gWindowFormats long enough to be used, and then ** it is removed. The 'WFMT' resource can be of any id other than 128, and must be ** named with the DocType, such as ABOT for the about box. (The name must always be ** 4 characters.) Passing in 0 for the DocType (OSType) disposes of however many ** were added. The number added is returned from the first time it is called. */ OSErr AddControlSet(WindowPtr window, OSType sftype, short visMode, short xoffset, short yoffset, CObjCtlHndl cco); /* ** ¶ Add a set of controls (and sets referenced by that set) to the window. ** ** INPUT: window ** sftype ** visMode ** xoffset ** yoffset ** IN/OUT cco ** RESULT: OSErr ** ** This function adds a set of controls (and sets referenced by that set) to the ** window. The control sets are created with the AppsToGo application editor. */ ControlHandle MakeControl(WindowPtr window, TreeObjHndl cobj, short visMode, short xoffset, short yoffset); /* ** ¶ Create a control based on the control definition object. ** ** INPUT: window ** cobj ** visMode ** xoffset ** yoffset ** RESULT: ControlHandle ** ** This function is used to create a control based on the control definition object. ** The control definition objects are created with the AppsToGo application editor. */ CObjCtlHndl GetControlSet(WindowPtr window, OSType sftype, ControlHandle *retDataCtl); /* ** ¶ Return Data control that has reference to all controls in control set. ** ** INPUT: window ** sftype ** OUTPUT: retDataCtl ** RESULT: CObjCtlHndl ** ** This function is called to return the handle of the Data control that has ** a reference to all of the controls in the control set. Once you get the ** Data control, you can then look at the data in the control to get the handle ** of the controls within the control set. */ void DisplayControlSet(WindowPtr window, OSType sftype, short visMode); /* ** ¶ Show or hide a set of controls. ** ** INPUT: window ** sftype ** visMode ** ** This function is used to show or hide a set of controls. */ void DrawControlSet(WindowPtr window, OSType sftype); /* ** ¶ Draw a set of controls. ** ** INPUT: window ** sftype ** ** This function is used to draw a set of controls. */ void DisposeControlSet(WindowPtr window, OSType sftype); /* ** ¶ Dispose a set of controls. ** ** INPUT: window ** sftype ** ** This function is used to dispose a set of controls. */ void DisposeControlFromSet(ControlHandle ctl, OSType sftype); /* ** ¶ Dispose a single control from a control set. ** ** INPUT: window ** sftype ** ** This function is used to dispose a single control from a control set. If it ** is the last control in the set, the dataCtl which contains the set ** information is also disposed of. */ Boolean DoAdjustMBARMenus(WindowPtr window, short menuBarID); /* ** ¶ Adjust all of the menus in the designated MBAR. ** ** INPUT: window ** menuBarID ** RESULT: Boolean ** ** This fuction is called to adjust all of the menus in the designated MBAR. ** The functions gets each menu handle, and then disables all of the menu items ** for that menu. It then calls the application to give the application the ** chance to enable the appropriate menu items. ** ** __________ ** ** Also see: DoAdjustMenus ** AppWannabe function where the menu handling chain ** begins. The application can do whatever it wants ** to adjust the menus, but the easiest thing is to ** just call DoAdjustMBARMenus. ** ** AdjustMenuItems ** AppWannabe function that DoAdjustMBARMenus calls ** for each menu. If the top window is not a document ** window, or if there is no window, then AdjustMenuItems ** is called directly. If the top window is a document ** window, then the document procPtr adjustMenuItemsProc ** is called. Note that adjustMenuItemsProc is initialized ** to AdjustMenuItems. This means that, unless you change ** it, AdjustMenuItems is called in all cases. */ OSErr OpenRuntimeOnlyAutoNewWindows(void); /* ** ¶ Open all windows that are correctly designated with AppsToGo application editor. ** ** RESULT: OSErr ** ** This function is used to open all of the windows that are correctly designated ** with the AppsToGo application editor. You should call this in your application ** at startup time if your application is editable with the AppsToGo ** application editor. */ OSErr NewDocumentWindow(FileRecHndl *frHndl, OSType sftype, Boolean incTitleNum); /* ** ¶ Calls NewDocument, and if successful, DoNewWindow. ** ** INPUT: sftype ** incTitleNum ** OUTPUT: frHndl ** RESULT: OSErr ** ** This call can be done as two separate calls (NewDocument / DoNewWindow). However, ** this function both creates the document, and then gives the document a window. ** It also handles errors and puts up an error window if something goes wrong. */ OSErr OpenDocumentWindow(FileRecHndl *frHndl, FSSpecPtr fileToOpen, char permission); /* ** ¶ Calls OpenDocument, and if successful, DoNewWindow. ** ** INPUT: fileToOpen ** permission ** OUTPUT: frHndl ** RESULT: OSErr ** ** This call can be done as two separate calls (OpenDocument / DoNewWindow). However, ** this function both creates the document, and then gives the document a window. ** It also handles errors and puts up an error window if something goes wrong. */ #ifdef __cplusplus } #endif #endif